iLand scripting

This page describes the use of Javascript as the scripting language used in iLand. Other important ways to interact with the model are, of course, using the iLand Software and the project settings.

technology

The scripting approach used in iLand relies on the scripting capabilities of the Qt-framework. Qt includes a fully ECMA compatible Javascript engine. Script execution is fast due to just-in-time compilation. Qt uses Googles V8-engine (powering the Google Chrome browser).
With Qt, it is quite easy to expose some dedicated functionality of C++ classes to the scripting context. In practise, this linking is done via specialized wrapper-code instead of exposing "full" model classes. 

using scripting

management

iLand includes two sub-systems that handle forest management:

• the Agent Based management Engine (ABE) is a powerful module that allows to simulate multiple management agents on a landscape. Agents can react to changes in the environment by changing management plans and can apply a variety of different management activities in a dynamically scheduled manner. The setup and application of ABE, however, is somewhat complex.
• the "base" management is simpler, but still versatile and allows a wide range of altering the forest in the model (extracting of trees, planting of trees, ...)

The approach in iLand relies on using Javascript as the "scripting language". The model exposes a set of objects and functions allowing a management script to interact with the model. ABE utilizes Javascript, but uses a more hybrid approach where computationally heavy parts are performed by C++ code.

For the base management, good starting points are the Object Management and Object Globals API documentation as well as available demo examples (like this or that).

In base management, a single javascript file is defined in the Project file and loaded during startup of the model. Every year the function manage() is called by iLand. The example shows a very simple and not particularly useful management routine:

function manage(year)
{
    print('management called in year ' + year);
}

The user needs to provide his or her own way of dispatching events over time. Examples of how this can be done are shown in the examples: management example: parallel management or management example: HJA fire history.

Note: the management happens quite early in a year.

controlling model output

The sheer amount of possible result data produced by models like iLand is potentially frightening, therefore a fine grained control over which results should be produced when is a useful weapon against drowning in data.
You can:

• enable and disable Outputs
• enable and disable Debug Outputs
• produce and save screenshots as image files
• export grids (e.g., the LIF-grid) as a ESRI ASCII file for later use in GIS applications

See the Object Globals for more details.

access points for scripts

iLand provides several ways how your scripts can be engaged by iLand.

user interface

The iLand user interface includes a simple "scripting console" that allows calling of Javascript functions. iLand can load automatically Javascript source code, when set in the system.javascript section of the Project file. In addition, the user can load Javscript source from the iLand user interface. 

time events

iLand provides an mechanism that updates the values of model settings? automatically over time. A typical use is to update the ambient CO2 concentration over time. The same mechanism can also be applied to inform iLand to call javascript functions at specific times.
The called function must be present in the context of the management script (i.e., be part of or be included from the management script file). One (small) difference to the management scripts (described above) is that time events occur even earlier in the year.

event handler

An event handler in the context of iLand is a Javascript function that is called when a specific event happens (technically an expression is evaluated in the scripting context of the management script). The following events are available in every iLand simulation:

Handler	Description
onAfterCreate	Called immediately before the first simulation year is executed.
onBeforeDestroy	Called after the simulation has ended and the model is shut down.
onYearBegin	called at the beginning of each simulation year.
onYearEnd	called after each simulated year.

 

In addition, this mechanism is used in the fire module to allow some evaluation work after a fire happened.

interactive mode

The iLand GUI allows for calling javascript functions when the model execution is paused (or before the model starts to run). This provides an easy way to, for instance, start script based evaluation tasks (an example is described in this blog post.